TypeScript Express 통합: 라우트 핸들러 타입 안전성

TypeScript는 현대 JavaScript 개발의 초석이 되어 코드 품질, 유지 관리성 및 확장성을 향상시키는 정적 타이핑 기능을 제공합니다. 널리 사용되는 Node.js 웹 애플리케이션 프레임워크인 Express.js와 함께 사용하면 TypeScript는 백엔드 API의 견고성을 크게 향상시킬 수 있습니다. 이 포괄적인 가이드에서는 TypeScript를 활용하여 Express.js 애플리케이션에서 라우트 핸들러 타입 안전성을 확보하는 방법을 살펴보고, 전 세계 사용자를 위한 강력하고 유지 관리 가능한 API 구축을 위한 실용적인 예제와 모범 사례를 제공합니다.

Express.js에서 타입 안전성이 중요한 이유

JavaScript와 같은 동적 언어에서는 오류가 런타임에 발생하는 경우가 많아 예기치 않은 동작과 디버그하기 어려운 문제가 발생할 수 있습니다. TypeScript는 정적 타이핑을 도입하여 이를 해결하므로 개발 중에 오류가 프로덕션 환경에 도달하기 전에 오류를 잡을 수 있습니다. Express.js의 맥락에서 타입 안전성은 요청 및 응답 객체, 쿼리 매개변수 및 요청 본문을 처리하는 라우트 핸들러에 특히 중요합니다. 이러한 요소를 잘못 처리하면 애플리케이션 충돌, 데이터 손상 및 보안 취약점이 발생할 수 있습니다.

• 초기 오류 감지: 개발 중에 타입 관련 오류를 잡아 런타임에 예상치 못한 상황이 발생할 가능성을 줄입니다.
• 향상된 코드 유지 관리성: 타입 주석을 통해 코드를 더 쉽게 이해하고 리팩터링할 수 있습니다.
• 향상된 코드 완성 및 도구 지원: IDE는 타입 정보를 통해 더 나은 제안과 오류 검사를 제공할 수 있습니다.
• 버그 감소: 타입 안전성은 함수에 잘못된 데이터 타입을 전달하는 것과 같은 일반적인 프로그래밍 오류를 방지하는 데 도움이 됩니다.

TypeScript Express.js 프로젝트 설정

라우트 핸들러 타입 안전성에 들어가기 전에 기본 TypeScript Express.js 프로젝트를 설정해 보겠습니다. 이는 우리 예제의 기초가 될 것입니다.

전제 조건

• Node.js 및 npm(Node Package Manager)이 설치되어 있어야 합니다. 공식 Node.js 웹사이트에서 다운로드할 수 있습니다. 최적의 호환성을 위해 최신 버전을 사용하십시오.
• Visual Studio Code와 같이 TypeScript를 잘 지원하는 코드 편집기가 필요합니다.

프로젝트 초기화

1. 새 프로젝트 디렉토리 생성: mkdir typescript-express-app && cd typescript-express-app
2. 새 npm 프로젝트 초기화: npm init -y
3. TypeScript 및 Express.js 설치: npm install typescript express
4. Express.js용 TypeScript 선언 파일 설치(타입 안전성에 중요): npm install @types/express @types/node
5. TypeScript 초기화: npx tsc --init (이렇게 하면 TypeScript 컴파일러를 구성하는 tsconfig.json 파일이 생성됩니다.)

TypeScript 구성

tsconfig.json 파일을 열고 적절하게 구성합니다. 다음은 샘플 구성입니다.

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

주목해야 할 주요 구성:

• target: ECMAScript 대상 버전을 지정합니다. es6가 좋은 시작점입니다.
• module: 모듈 코드 생성을 지정합니다. commonjs는 Node.js에 대한 일반적인 선택입니다.
• outDir: 컴파일된 JavaScript 파일의 출력 디렉토리를 지정합니다.
• rootDir: TypeScript 소스 파일의 루트 디렉토리를 지정합니다.
• strict: 향상된 타입 안전성을 위해 모든 엄격한 타입 검사 옵션을 활성화합니다. 이것은 적극 권장됩니다.
• esModuleInterop: CommonJS와 ES 모듈 간의 상호 운용성을 활성화합니다.

진입점 생성

src 디렉토리를 만들고 index.ts 파일을 추가합니다.

mkdir src
touch src/index.ts

기본 Express.js 서버 설정으로 src/index.ts를 채웁니다.

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, TypeScript Express!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

빌드 스크립트 추가

TypeScript 코드를 컴파일하려면 package.json 파일에 빌드 스크립트를 추가합니다.

"scripts": {
  "build": "tsc",
  "start": "node dist/index.js",
  "dev": "npm run build && npm run start"
}

이제 npm run dev를 실행하여 서버를 빌드하고 시작할 수 있습니다.

라우트 핸들러 타입 안전성: 요청 및 응답 타입 정의

라우트 핸들러 타입 안전성의 핵심은 Request 및 Response 객체에 대한 타입을 올바르게 정의하는 데 있습니다. Express.js는 쿼리 매개변수, 요청 본문 및 라우트 매개변수의 타입을 지정할 수 있는 이러한 객체에 대한 제네릭 타입을 제공합니다.

기본 라우트 핸들러 타입

이름을 쿼리 매개변수로 예상하는 간단한 라우트 핸들러부터 시작하겠습니다.

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

interface NameQuery {
  name: string;
}

app.get('/hello', (req: Request, res: Response) => {
  const name = req.query.name;

  if (!name) {
    return res.status(400).send('Name parameter is required.');
  }

  res.send(`Hello, ${name}!`);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• Request<any, any, any, NameQuery>는 요청 객체의 타입을 정의합니다.
• 첫 번째 any는 라우트 매개변수(예: /users/:id)를 나타냅니다.
• 두 번째 any는 응답 본문 타입을 나타냅니다.
• 세 번째 any는 요청 본문 타입을 나타냅니다.
• NameQuery는 쿼리 매개변수의 구조를 정의하는 인터페이스입니다.

NameQuery 인터페이스를 정의하면 TypeScript는 이제 req.query.name 속성이 존재하고 string 타입인지 확인할 수 있습니다. 존재하지 않는 속성에 액세스하거나 잘못된 타입의 값을 할당하려고 하면 TypeScript에서 오류를 표시합니다.

요청 본문 처리

요청 본문을 수락하는 라우트(예: POST, PUT, PATCH)의 경우 요청 본문에 대한 인터페이스를 정의하고 Request 타입에서 사용할 수 있습니다.

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

app.use(bodyParser.json()); // JSON 요청 본문 파싱에 중요

interface CreateUserRequest {
  firstName: string;
  lastName: string;
  email: string;
}

app.post('/users', (req: Request, res: Response) => {
  const { firstName, lastName, email } = req.body;

  // 요청 본문 유효성 검사
  if (!firstName || !lastName || !email) {
    return res.status(400).send('Missing required fields.');
  }

  // 사용자 생성 처리(예: 데이터베이스에 저장)
  console.log(`Creating user: ${firstName} ${lastName} (${email})`);

  res.status(201).send('User created successfully.');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• CreateUserRequest는 예상되는 요청 본문의 구조를 정의합니다.
• app.use(bodyParser.json())은 JSON 요청 본문을 파싱하는 데 중요합니다. 없으면 req.body가 정의되지 않습니다.
• 이제 Request 타입은 Request<any, any, CreateUserRequest>이며, 이는 요청 본문이 CreateUserRequest 인터페이스를 준수해야 함을 나타냅니다.

TypeScript는 이제 req.body 객체에 예상되는 속성(firstName, lastName 및 email)이 포함되어 있고 해당 타입이 올바른지 확인합니다. 이는 잘못된 요청 본문 데이터로 인해 발생하는 런타임 오류의 위험을 크게 줄입니다.

라우트 매개변수 처리

매개변수가 있는 라우트(예: /users/:id)의 경우 라우트 매개변수에 대한 인터페이스를 정의하고 Request 타입에서 사용할 수 있습니다.

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

interface UserParams {
  id: string;
}

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

const users: User[] = [
  { id: '1', firstName: 'John', lastName: 'Doe', email: 'john.doe@example.com' },
  { id: '2', firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com' },
];

app.get('/users/:id', (req: Request, res: Response) => {
  const userId = req.params.id;

  const user = users.find(u => u.id === userId);

  if (!user) {
    return res.status(404).send('User not found.');
  }

  res.json(user);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• UserParams는 라우트 매개변수의 구조를 정의하여 id 매개변수가 문자열이어야 함을 지정합니다.
• 이제 Request 타입은 Request<UserParams>이며, 이는 req.params 객체가 UserParams 인터페이스를 준수해야 함을 나타냅니다.

TypeScript는 이제 req.params.id 속성이 존재하고 string 타입인지 확인합니다. 이는 존재하지 않는 라우트 매개변수에 액세스하거나 잘못된 타입으로 사용하는 경우 발생하는 오류를 방지하는 데 도움이 됩니다.

응답 타입 지정

요청 타입 안전성에 집중하는 것이 중요하지만 응답 타입을 정의하면 코드 명확성이 향상되고 불일치를 방지하는 데 도움이 됩니다. 응답에서 다시 보내는 데이터의 타입을 정의할 수 있습니다.

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

const users: User[] = [
  { id: '1', firstName: 'John', lastName: 'Doe', email: 'john.doe@example.com' },
  { id: '2', firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com' },
];

app.get('/users', (req: Request, res: Response) => {
    res.json(users);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

여기서 Response<User[]>는 응답 본문이 User 객체의 배열이어야 함을 지정합니다. 이렇게 하면 API 응답에서 올바른 데이터 구조를 일관되게 보내는 데 도움이 됩니다. User[] 타입을 준수하지 않는 데이터를 보내려고 하면 TypeScript에서 경고를 표시합니다.

미들웨어 타입 안전성

미들웨어 함수는 Express.js 애플리케이션에서 교차 절단 문제를 처리하는 데 필수적입니다. 미들웨어에서 타입 안전성을 보장하는 것은 라우트 핸들러에서와 마찬가지로 중요합니다.

미들웨어 함수 타이핑

TypeScript에서 미들웨어 함수의 기본 구조는 라우트 핸들러의 구조와 유사합니다.

import express, { Request, Response, NextFunction } from 'express';

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // 인증 로직
  const isAuthenticated = true; // 실제 인증 확인으로 대체

  if (isAuthenticated) {
    next(); // 다음 미들웨어 또는 라우트 핸들러로 진행
  } else {
    res.status(401).send('Unauthorized');
  }
}

const app = express();
const port = 3000;

app.use(authenticationMiddleware);

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, authenticated user!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• NextFunction은 Express.js에서 제공하는 타입으로, 체인의 다음 미들웨어 함수를 나타냅니다.
• 미들웨어 함수는 라우트 핸들러와 동일한 Request 및 Response 객체를 사용합니다.

요청 객체 보강

경우에 따라 미들웨어에서 Request 객체에 사용자 정의 속성을 추가할 수 있습니다. 예를 들어 인증 미들웨어는 요청 객체에 user 속성을 추가할 수 있습니다. 타입 안전한 방식으로 이 작업을 수행하려면 Request 인터페이스를 보강해야 합니다.

import express, { Request, Response, NextFunction } from 'express';

interface User {
  id: string;
  username: string;
  email: string;
}

// Request 인터페이스 보강
declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // 인증 로직(실제 인증 확인으로 대체)
  const user: User = { id: '123', username: 'johndoe', email: 'john.doe@example.com' };
  req.user = user; // 요청 객체에 사용자 추가
  next(); // 다음 미들웨어 또는 라우트 핸들러로 진행
}

const app = express();
const port = 3000;

app.use(authenticationMiddleware);

app.get('/', (req: Request, res: Response) => {
  const username = req.user?.username || 'Guest';
  res.send(`Hello, ${username}!`);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• 전역 선언을 사용하여 Express.Request 인터페이스를 보강합니다.
• Request 인터페이스에 타입 User의 선택적 user 속성을 추가합니다.
• 이제 TypeScript에서 불만을 제기하지 않고 라우트 핸들러에서 req.user 속성에 액세스할 수 있습니다. req.user?.username의 `?`는 사용자가 인증되지 않은 경우를 처리하여 잠재적인 오류를 방지하는 데 중요합니다.

TypeScript Express 통합 모범 사례

Express.js 애플리케이션에서 TypeScript의 이점을 극대화하려면 다음 모범 사례를 따르십시오.

• 엄격 모드 활성화: tsconfig.json 파일에서 "strict": true 옵션을 사용하여 모든 엄격한 타입 검사 옵션을 활성화합니다. 이는 잠재적인 오류를 조기에 잡고 더 높은 수준의 타입 안전성을 보장하는 데 도움이 됩니다.
• 인터페이스 및 타입 별칭 사용: 인터페이스 및 타입 별칭을 정의하여 데이터 구조를 나타냅니다. 이렇게 하면 코드를 더 쉽게 읽고 유지 관리할 수 있습니다.
• 제네릭 타입 사용: 제네릭 타입을 활용하여 재사용 가능하고 타입 안전한 컴포넌트를 만듭니다.
• 단위 테스트 작성: 단위 테스트를 작성하여 코드의 정확성을 확인하고 타입 주석이 정확한지 확인합니다. 테스트는 코드 품질을 유지하는 데 매우 중요합니다.
• 린터 및 포맷터 사용: 린터(예: ESLint)와 포맷터(예: Prettier)를 사용하여 일관된 코딩 스타일을 적용하고 잠재적인 오류를 잡습니다.
• any 타입 피하기: any 타입의 사용을 최소화합니다. any 타입은 타입 검사를 우회하고 TypeScript를 사용하는 목적을 무효화합니다. 절대적으로 필요한 경우에만 사용하고 가능하면 더 구체적인 타입 또는 제네릭을 사용하는 것이 좋습니다.
• 프로젝트를 논리적으로 구성: 기능을 기반으로 프로젝트를 모듈 또는 폴더로 구성합니다. 이렇게 하면 애플리케이션의 유지 관리성과 확장성이 향상됩니다.
• 종속성 주입 사용: 종속성 주입 컨테이너를 사용하여 애플리케이션의 종속성을 관리하는 것이 좋습니다. 이렇게 하면 코드를 더 쉽게 테스트하고 유지 관리할 수 있습니다. InversifyJS와 같은 라이브러리가 널리 사용됩니다.

Express.js를 위한 고급 TypeScript 개념

데코레이터 사용

데코레이터는 클래스 및 함수에 메타데이터를 추가하는 간결하고 표현력이 풍부한 방법을 제공합니다. 데코레이터를 사용하여 Express.js에서 라우트 등록을 간소화할 수 있습니다.

먼저 compilerOptions에 "experimentalDecorators": true를 추가하여 tsconfig.json 파일에서 실험적 데코레이터를 활성화해야 합니다.

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "experimentalDecorators": true
  }
}

그런 다음 사용자 정의 데코레이터를 만들어 라우트를 등록할 수 있습니다.

import express, { Router, Request, Response } from 'express';

function route(method: string, path: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    if (!target.__router__) {
      target.__router__ = Router();
    }

    target.__router__[method](path, descriptor.value);
  };
}

class UserController {
  @route('get', '/users')
  getUsers(req: Request, res: Response) {
    res.send('List of users');
  }

  @route('post', '/users')
  createUser(req: Request, res: Response) {
    res.status(201).send('User created');
  }

  public getRouter() {
    return this.__router__;
  }
}

const userController = new UserController();

const app = express();
const port = 3000;

app.use('/', userController.getRouter());

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• route 데코레이터는 HTTP 메서드와 경로를 인수로 사용합니다.
• 클래스와 연결된 라우터에서 데코레이트된 메서드를 라우트 핸들러로 등록합니다.
• 이렇게 하면 라우트 등록이 간소화되고 코드를 더 쉽게 읽을 수 있습니다.

사용자 정의 타입 가드 사용

타입 가드는 특정 범위 내에서 변수의 타입을 좁히는 함수입니다. 사용자 정의 타입 가드를 사용하여 요청 본문 또는 쿼리 매개변수의 유효성을 검사할 수 있습니다.

interface Product {
    id: string;
    name: string;
    price: number;
}

function isProduct(obj: any): obj is Product {
    return typeof obj === 'object' &&
           obj !== null &&
           typeof obj.id === 'string' &&
           typeof obj.name === 'string' &&
           typeof obj.price === 'number';
}

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

app.use(bodyParser.json());

app.post('/products', (req: Request, res: Response) => {
    if (!isProduct(req.body)) {
        return res.status(400).send('Invalid product data');
    }

    const product: Product = req.body;
    console.log(`Creating product: ${product.name}`);
    res.status(201).send('Product created');
});

app.listen(port, () => {
    console.log(`Server running at http://localhost:${port}`);
});

이 예에서:

• isProduct 함수는 객체가 Product 인터페이스를 준수하는지 확인하는 사용자 정의 타입 가드입니다.
• /products 라우트 핸들러 내에서 isProduct 함수를 사용하여 요청 본문의 유효성을 검사합니다.
• 요청 본문이 유효한 제품인 경우 TypeScript는 if 블록 내에서 req.body가 Product 타입임을 압니다.

API 설계 시 전역 고려 사항 처리

전 세계 사용자를 위한 API를 설계할 때는 접근성, 사용 편의성 및 문화적 감수성을 보장하기 위해 몇 가지 요소를 고려해야 합니다.

• 지역화 및 국제화(i18n 및 L10n):
  • 콘텐츠 협상: Accept-Language 헤더를 기반으로 콘텐츠 협상을 통해 여러 언어 및 지역을 지원합니다.
  • 날짜 및 시간 형식 지정: 다양한 지역에서 모호성을 피하기 위해 날짜 및 시간 표시에 ISO 8601 형식을 사용합니다.
  • 숫자 형식 지정: 사용자의 로케일에 따라 숫자 형식 지정(예: 소수 구분 기호 및 천 단위 구분 기호)을 처리합니다.
  • 통화 처리: 여러 통화를 지원하고 필요한 경우 환율 정보를 제공합니다.
  • 텍스트 방향: 아랍어 및 히브리어와 같은 오른쪽에서 왼쪽(RTL) 언어를 수용합니다.
• 시간대:
  • 서버 측에서 날짜 및 시간을 UTC(Coordinated Universal Time)로 저장합니다.
  • 사용자가 선호하는 시간대를 지정하고 클라이언트 측에서 그에 따라 날짜 및 시간을 변환할 수 있도록 합니다.
  • moment-timezone과 같은 라이브러리를 사용하여 시간대 변환을 처리합니다.
• 문자 인코딩:
  • 다양한 언어의 광범위한 문자를 지원하기 위해 모든 텍스트 데이터에 UTF-8 인코딩을 사용합니다.
  • 데이터베이스 및 기타 데이터 저장 시스템이 UTF-8을 사용하도록 구성되어 있는지 확인합니다.
• 접근성:
  • 접근성 지침(예: WCAG)을 준수하여 장애가 있는 사용자가 API에 액세스할 수 있도록 합니다.
  • 이해하기 쉬운 명확하고 설명적인 오류 메시지를 제공합니다.
  • API 문서에서 의미론적 HTML 요소 및 ARIA 속성을 사용합니다.
• 문화적 감수성:
  • 모든 사용자가 이해하지 못할 수 있는 문화적으로 구체적인 참조, 관용구 또는 유머를 사용하지 마십시오.
  • 의사 소통 스타일과 선호도에서 문화적 차이를 염두에 두십시오.
  • API가 다양한 문화 그룹에 미치는 잠재적 영향을 고려하고 고정 관념이나 편견을 영속화하지 마십시오.
• 데이터 개인 정보 보호 및 보안:
  • GDPR(General Data Protection Regulation) 및 CCPA(California Consumer Privacy Act)와 같은 데이터 개인 정보 보호 규정을 준수합니다.
  • 사용자 데이터를 보호하기 위해 강력한 인증 및 권한 부여 메커니즘을 구현합니다.
  • 전송 중 및 유휴 상태에서 중요한 데이터를 암호화합니다.
  • 사용자에게 자신의 데이터에 대한 제어 권한을 제공하고 자신의 데이터에 액세스, 수정 및 삭제할 수 있도록 합니다.
• API 문서:
  • 이해하고 탐색하기 쉬운 포괄적이고 잘 정리된 API 문서를 제공합니다.
  • Swagger/OpenAPI와 같은 도구를 사용하여 대화형 API 문서를 생성합니다.
  • 다양한 청중을 위해 여러 프로그래밍 언어로 코드 예제를 포함합니다.
  • 더 넓은 청중에게 다가가기 위해 API 문서를 여러 언어로 번역합니다.
• 오류 처리:
  • 구체적이고 유용한 오류 메시지를 제공합니다. "Something went wrong."과 같은 일반적인 오류 메시지를 피하십시오.
  • 표준 HTTP 상태 코드를 사용하여 오류 유형을 나타냅니다(예: 잘못된 요청의 경우 400, 권한이 없는 경우 401, 내부 서버 오류의 경우 500).
  • 문제를 추적하고 디버그하는 데 사용할 수 있는 오류 코드 또는 식별자를 포함합니다.
  • 디버깅 및 모니터링을 위해 서버 측에서 오류를 기록합니다.
• 속도 제한: API를 남용으로부터 보호하고 공정한 사용을 보장하기 위해 속도 제한을 구현합니다.
• 버전 관리: 이전 버전과 호환되는 변경을 허용하고 기존 클라이언트의 손상을 방지하기 위해 API 버전 관리를 사용합니다.

결론

TypeScript Express 통합은 백엔드 API의 안정성과 유지 관리성을 크게 향상시킵니다. 라우트 핸들러 및 미들웨어에서 타입 안전성을 활용하여 개발 프로세스 초기에 오류를 잡고 전 세계 사용자를 위한 보다 강력하고 확장 가능한 애플리케이션을 구축할 수 있습니다. 요청 및 응답 타입을 정의하면 API가 일관된 데이터 구조를 준수하여 런타임 오류의 가능성을 줄입니다. 엄격 모드 활성화, 인터페이스 및 타입 별칭 사용, 단위 테스트 작성과 같은 모범 사례를 준수하여 TypeScript의 이점을 극대화하는 것을 잊지 마십시오. API가 전 세계적으로 액세스 가능하고 사용 가능한지 확인하려면 항상 지역화, 시간대 및 문화적 감수성과 같은 전역 요소를 고려하십시오.